home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
PROGRAM
/
PCW_C.ARJ
/
PCW.DOC
< prev
next >
Wrap
Text File
|
1991-12-29
|
81KB
|
2,086 lines
----L----l----+----2----+----3----+----4----+----5----+----6----+----j----J----8
PC Windows Phase I
Copyright (c) 1989, 1990
By Stan Milam
Introduction
PC windows, called PCW, is a library of C and assembler routines
designed to give you control over the video of your computer. PCW
has been written to work with the IBM family of personal computers
and 100% compatibles using Microsoft C version 5.0, Turbo C version
1.5 and up, and Mix Software's Power C version 1.1.6 and up. PCW is
a powerful tool designed to give you, the C programmer, complete
power over the video hardware of your PC. PCW features automatic
detection of the video hardware, windows, quick direct memory screen
writes, video BIOS support, MOUSE support, keyboard support, pop-up
menus (using the Mouse), and a Lotus style menu with a twist.
There is nothing fancy about the format of this document. What
I will tell you here will concern PCW global variables, PCW
functions, and PCW manifest constants. Global variables are few - the
fewer the better. All functions will include a description of use
and an example program. Manifest constants will have to live with
just a description.
Compiling and Linking with PC Windows
How you compile and link with PCW depends on the compiler you are
using and how you have set up your computer system and the DOS
environment variables used by your compiler. We will examine
compiling and linking with Power C, Microsoft C, and Turbo C with
both the command line version and the Integrated Environment version.
The Header Files
In all cases you should copy the PC Windows header files into the
include directory used by your compiler. The include directory will
be different for each compiler. If you have any doubts where or what
your include directory is refer to your compiler manual. Listed
below are the normal location and name of the include directory for
each compiler:
c:\powerc /* Or whatever */
c:\include /* Microsoft C */
c:\turboc\include /* Turbo C */
Now perform the following copy operations:
copy *.h [to one of the directories listed above]
copy *.i [to one of the directories listed above]
The Libraries
There should be three files with the .LIB extension on the
distribution diskette. These .LIB files match to the compilers as
follows:
mspcwmm.lib - Microsoft C V5.0 and up and Quick C.
tcpcwmm.lib - Turbo C
pcpcwmm.lib - Power C
ztpcwmm.lib - Zortech C V2.1
These are medium model libraries and need to be copied to the
directory that you have set up for use by the linker for your
libraries. Here are some examples of what we mean:
copy tc*.lib c:\turboc\lib /* Turbo C */
copy ms*.lib c:\lib /* Microsoft */
copy pc*.lib c:\powerc /* Power C */
copy zt*.lib c:\zt\lib /* Zortech */
Power C
Here we examine how you might compile using the Power C compiler.
First lets assume you have all of your Power C executables, header
files, and libraries in a directory on C: drive called POWERC. The
c:\powerc directory will need to be included in the DOS PATH
statement. You may set the DOS PATH in the AUTOEXEC.BAT file which
is executed when the computer boots up as follows:
set path=c:\dos;c:\powerc;
This will ensure that DOS finds the Power C executables when you
invoke them. However, before you can compile you must set some DOS
environment variables that will be used by the compiler to identify
what directories you have placed header files and libraries. The
environment variables are LIBRARY, PCOPTIONS, LIBNAMES. LIBNAMES
only pertains if you are using Power C version 1.2 or later. The
LIBRARY variable will tell the Power C linker what directory you have
placed the standard linkage libraries, while PCOPTIONS can be used to
point the compiler to a directory where header files can be found,
and LIBNAMES will be used to point the Power C linker to
external libraries like PC Windows. Again, you must set these
variables in the AUTOEXEC.BAT using the DOS SET command. Assuming
we wanted to do all of our work out of the C:\POWERC directory we
would set our environment variables as follows:
SET PCOPTIONS=/IC:\POWERC
SET LIBRARY=C:\POWERC
SET LIBNAMES=C:\POWERC\PCPCWMM.LIB /* version 1.2 and up only */
If you are using a version of Power C earlier than version 1.2 you
will not be able to use the LIBNAMES variable, although it does not
hurt to add it in case you plan to upgrade. If you can not use the
LIBNAMES variable you must use the following command line to link
your program to the PC Windows library:
pcl myprog;c:\powerc\pcpcwmm.lib
You must do this every time you link (its enough to make you want
to upgrade!).
Turbo C
Okay, so you don't want to mess around with Power C -- you want to
use Turbo C. First you will need to make sure the Turbo C directory
is in the DOS PATH. What happens next depends on which version of
the compiler you are going to use. If you are a very serious
programmer you will probably use the command line version (TCC) and
if you are a casual or beginning C programmer you will probably use
the Integrated Environment (TC). We will cover both, but separately.
First if you are using the command line version you will need to
check the contents of a file called TURBOC.CFG. This file points
Turbo C (TCC) to the directories where your include files and
libraries are. They might look something like this:
-IC:\TURBOC\INCLUDE
-LC:\TURBOC\LIB
The TURBOC.CFG file contains information that you would like the
compiler to use every time you compile. For example, if you always
wanted type char to default to unsigned every time you compiled you
would add the -K option to the TURBOC.CFG file. As it is, it should
always contain the PATH to the include directory and the library
directory. Now, you should copy the PC Windows Libraries for Turbo
C to the C:\TURBOC\LIB directory (above).
copy tcpcw*.lib c:\turboc\lib
The command line compiler can not only compile your program it can
link it too. For example:
tcc -mm -K menudemo pdemo ldemo tcpcwmm.lib
The above example would compile the Menu Demo program in the medium
memory model and link it with the PC Windows library, TCPCWMM.LIB.
Turbo C Integrated Environment:
If you are using the Integrated Environment to edit, compile, link,
and run your program you will need to do a couple of extra things to
make a program work with PC Windows. First you will need to set the
memory model you wish to compile with to medium using the key
commands ALT O/C/M (We use medium memory model in these directions
because it is the only library we ship on the distribution diskette).
Next you need to be sure the Integrated Environment is using the
correct directories. Use the key commands ALT O/D to get to the
directories window and make sure the INCLUDE DIRECTORIES: is set to
C:\TURBOC\INCLUDE, and the LIBRARY DIRECTORY: is set to
C:\TURBOC\LIB. Now, you are almost ready to run with PC Windows, but
first we need a way to tell the Integrated Environment that we will
need to link to a user library. To do this we use Turbo C's Project
Manager. It is very simple to do: first you create and edit a new
file in which you place all the names of your source modules and
include the name of the PC Windows library, TCPCWMM.LIB, and finally
save the file with the name of your main program with a .PRJ
extension. Next use the key commands ALT /P/P to notify the
Integrated Environment of your project name. Now you are ready to
run. For example to run the example program MENUDEMO out of the
Integrated Environment you would create a project file called
MENUDEMO.PRJ with these contents:
MENUDEMO.C
PDEMO.C
LDEMO.C
TCPCWMM.LIB
Next you would set the PROJECT FILE to MENUDEMO.PRJ. Now you would
edit MENUDEMO.C and run or compile as a normal program and Turbo C
would know to compile the three C source files and link with
TCPCWMM.LIB.
Microsoft C V5.1
Okay, now you've hit the big time and are using Microsoft C V5.0 or
greater. To use PC Windows with MSC you must be sure the header
files are copied to the INCLUDE directory and the PCW library is
copied to the LIB directory.
copy *.h c:\include
copy *.i c:\include
copy mspcw*.lib c:\lib
Now you are ready to write and compile programs using PC Windows. To
compile and link with PC Windows in one step you may use the
following command line as a model:
cl -AM yourpgm.c /link mspcwam.lib /* OR..... */
cl -AM yourpgm.c mspcwam.lib
For example to compile and link the MENUDEMO program you would supply
the following command line:
cl -AM menudemo.c pdemo.c ldemo.c /link mspcwam
NOTE: If your are using Microsoft's Quick C version 2.0 you may use
the exact same command lines shown above to compile and link your
programs with one exception: change cl to qcl. If you are using
version 1.x of Quick C you may still compile and link with the
MSPCWAM library, but the command line options will be different.
Please refer to your Quick C manual for details, and please consider
an upgrade to version 2.0.
Quick C Version 2.0 Integrated Environment:
Here we discuss using the integrated environment using Microsoft's
Quick C version 2.0. Note you can use version 1.x of Quick C but
there are very big differences between the two versions. We only
discuss version 2.0, but the idea is the same. If you are using
version 1.x of Quick C refer to MULTIPLE-MODULE PROGRAMS in chapter 6
of your Quick C manual. To compile and link with PC Windows and Quick
C's integrated environment you will have to set up a program list for
every program you run. Do not despair as this is a simple operation.
Futhermore, you will need to set your memory model to medium. From
Quick C's menu you will need to select the MAKE option (ALT M) and
then select the (S)et Program List option. Quick C will show you
a list of available program lists already saved on disk. If
your program is contained in one of these lists then select it and
continue on your merry way. However, if this is the first time
you are compiling your program you will need to create a new
program list. In the program list you will need to include every
source code member needed and one of these members will need to be
MSPCWAM.LIB. This will notify Quick C that your program needs to
be linked with the PC Windows library. For example, to compile,
link, and run the menudemo program from the Integrated Environment
you would build a list with the following members:
menudemo.c
ldemo.c
pdemo.c
mspcwam.lib
Once you have built this list you will need to save it. Once saved
you are ready to compile (provided you have set your memory model to
medium).
For information concerning program lists refer to the section labeled
Creating a Program List in your UP AND RUNNING manual.
The Function Classes
The functions in PCW can be divided into classes. First come
the "Quick" screen write functions. These functions all start with
the letter "q". These functions do as their name implies - write to
the screen very, very, very quickly. There is no character filtering
with these functions. This means if you send the string "Hello
World\n" to the screen the '\n' newline character would not be
filtered and would appear as a funny little glitch on your video
screen. Next would come the window functions. All of the window
functions, with the exception of wexplode, wpush, and wframe, require
a window handle as an argument. A window handle is obtained by using
one of the above functions. PCW supports overlapping windows, and
any window that has been established can be addressed at any time,
even if the windows are overlapped. PCW will make the window that is
addressed the "active" window. This means if the window is
overlapped and addressed with any window function, that window will
be "floated" to the top and made to be the active window. For
example, you are using three windows concurrently on the screen and
your window handles are wnd1, wnd2, and wnd3. The third window would
be the active window. Now suppose they overlapped as shown:
+---------------+
| wnd1 |
| |
| +----------------+
| | wnd2 |
| | |
| | +------------+
| | | wnd3 |
| | | |
| | +------------+
+-----| |
+----------------+
Now suppose you addressed wnd2 with a window function. The windows
would be reordered as follows:
+---------------+
| wnd1 |
| +----------------+
| | wnd2 |
| | |
| | |----+
| | |3 |
| | | |
| | |----+
+------| |
+----------------+
Notice that wnd2 now covers wnd3 as well as wnd1. The only time this
will not work is when a window is hidden. If it is hidden the the
window function is ignored. It is wise to keep your windows simple
and try to avoid overlaps to keep them from thrashing around on the
screen and wasting time.
Another class of functions would be the Mouse functions. These
functions implement usage of a Microsoft compatible Mouse. Other
function classes would be, Keyboard, BIOS dependant, Miscellaneous,
and PCW Environment functions.
Global Variables
A few words about global variables declared and maintained by PC
Windows is in order. The keywords here are "maintained by PC
Windows". What this means is you should let PC Windows worry about
what values are stored in them. You may inquire as to what their
values are, but NEVER, NEVER, NEVER change the values in your program
or it is guaranteed PC Windows will not work properly. The global
variables are declared in the PCWPROTO.H header file. Following is a
description of each variable and the usage of each.
_adaptor
Description: The _adaptor global variable is set by the PCW startup
code to a value that indicates what video adaptor is used on the host
system. The manifest constants MDA, CGA, EGA, VGA can be used by
your program to query the value in the _adaptor variable. For
example, if (_adaptor > CGA), could be used to determine if your are
dealing with an EGA or VGA adapter.
_monitor
Description: The _monitor global variable is set by the PCW startup
code to a value that indicates whether the monitor is a color or
monochrome monitor. The manifest constants MONO and COLOR can be
used to determine the value of the _monitor variable.
_video_ram
Description: The _video_ram global variable is set by the PCW
startup code to a value that indicates the amount of RAM that is
allocated by the host video system for use by the video system. The
value in this variable is expressed in K bytes.
mpresent
Description: The mpresent variable is set by the init_mouse()
function when it is determined whether there is a mouse attached to
the host system. This is a neccessary and useful variable in that
the Mouse software is independent of PC Windows and it is helpful
to know if the Mouse is home or not. For example, if your
program uses the Mouse you will want to check to see if the Mouse
is home before using any PCW function. Example:
if (mpresent) hide_mouse(); /* if Mouse home hide it */
wnd = wpop(wnd); /* Remove the window */
if (mpresent) show_mouse(); /* Reshow the Mouse if home */
Vbump
Description: The Vbump variable is set by PCW at startup and is
updated continually by PCW every time one of PCW's functions is
called. It is used internally by PCW in the calculation of offsets
into video memory.
CheckSnow
Description: The CheckSnow variable is set by PCW at startup and is
used by PC Windows' assembly modules whether to execute the code to
reduce the snow that appears when using a CGA adapter.
Window Functions
wframe()
#include <pcwproto.h>
WNDPTR *wframe(int ur,int uc,int lr, int lc,int fcolr,int bcolr);
Description: The wframe() function will frame a window at the
specified coordinates. Ur, uc, lr, and lc are the upper and lower
rows and columns of the window. Fcolr and bcolr are the foreground
and background colors of the window. The window is added into an
internal list of windows. The type of frame and its color are
determined by the functions setborder() and bordercolor respectively.
Returns: A pointer to type WNDPTR, which will be used as a handle to
the window on all subsequent window operations. If wframe() could
not create the window for any reason a NULL pointer will be returned.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
setborder(DOUBLEALL);
bordercolor(WHITE,BLUE);
wnd = wframe(6,20,18,60,BLUE,LIGHTGRAY);
if (!wnd) exit(3);
swait(5);
wnd = wpop(wnd);
}
wexplode()
#include <pcwproto.h>
WNDPTR *wexplode(int ur,int uc,int lr,int lc,int fcolor,int bcolor);
Description: The wexplode() function is very similar to the wframe
function. It also frames a window at the specified coordinates and
returns a window handle. The only difference is the window explodes
from a central point specified by the coordinates quickly, and
smoothly. The border type and color is determined by the values last
passed to the setborder() and bordercolor() functions respectively.
Returns: A pointer of type WNDPTR, which will be used as a window
handle on all subsequent window functions that affect the window.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
setborder(DOUBLEALL);
bordercolor(WHITE,BLUE);
wnd = wexplode(6,20,18,60,BLUE,LIGHTGRAY);
if (!wnd) exit(3);
swait(5);
wnd = wpop(wnd);
}
wpush()
#include <pcwproto.h>
WNDPTR *wpush(int urow, int ucol, int lrow, int lcol);
Description: The wpush() function will save the contents of the
screen specified by the coordinates. The contents of the "window"
can be restored at a later time. The "pushed" area is treated just
like any other window by the window routines.
Returns: A pointer to type WNDPTR, which can be used as a handle to
the window in subsequent window operations. Returns a NULL pointer
if the operation failed for any reason.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
WNDPTR *savewnd;
int mxr, mxc;
if (!get_video_state(&mxr,&mxc)) exit(3);
savewnd = wpush(1,1,mxr,mxc); vcls();
qfill(6,20,18,60,RED,RED,32);
swait(5); savewnd = wpop(savewnd);
}
wprintf()
#include <pcwproto.h>
int wprintf(WNDPTR *wnd, int row, int col, char *format,...);
Description: The wprintf() function writes formatted output strings
to a specified window similar to the standard printf() function.
The WNDPTR pointer is a handle to the window. The row & col
variables specify the row and column IN THE WINDOW that you wish to
place the output, and the format string is used just as a format
string in printf(). The color of the output is determined by the
color attributes used when framing or exploding the window. The
color attributes can be changed by using the set_wnd_attr() function.
Returns: A non-zero value is returned if the function was completed
successfully and a zero value will be returned for any reason the
function could not perform its operation.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
static char format[] = "This is a format string. Line = %d";
WNDPTR *wnd;
int lcv;
pcwinit(AUTOEXIT);
wnd = wframe(6,10,18,70,RED,LIGHTGRAY);
if (!wnd) exit(3);
for (lcv = 1; lcv < 10; lcv++)
wprintf(wnd,lcv,CENTER,format,lcv);
swait(5); wnd = wpop(wnd);
}
wputs()
#include <pcwproto.h>
int wputs(WNDPTR *wnd, int row, int col, char str[]);
Description: Wputs() writes a string of characters into the
specified window at the specified row and column in the window. The
WNDPTR pointer is a handle to the specified window. The row and col
variables are the specified row and column INSIDE THE WINDOW. The
character string str[] is the string to be written in the window. If
the string is too long to be displayed entirely in the window then it
is truncated. The color of the characters in the window are
determined by the colors specified when the window was created with
wframe, wexplode, or wpush. If the window was created with wpush the
default colors of LIGHTGRAY on BLACK are used. If the window is
overlapped by any other window then the window will be "floated" to
the top and made the top window. If row and column are outside of
the window boundaries the string will not be printed and a zero
value will be returned.
Returns: Non-zero if completed successfully.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
static char hello[] = "Hello World!! PC Windows Here!";
WNDPTR wnd;
pcwinit(NOEXIT);
wnd = wexplode(6,10,18,70,BLUE,LIGHTGRAY);
wputs(wnd,5,CENTER,hello);
swait(5); wnd = wpop(wnd);
}
wtitle()
#include <pcwproto.h>
int wtitle(WNDPTR wnd,int top_bottom,int mid_left_right,char *title);
Description: The wtitle() function will title a window that
has been previously established. The WNDPTR pointer is a handle to
the window to be titled. The top_bottom parameter is used to
specify whether the title is to be placed at the top or bottom of the
window. Use the manifest constants TOP or BOTTOM to specify the
value. The mid_left_rite parameter specifies whether the title
will be at the left, or in the middle, or at the right of the
window. Use the manifest constants LEFT, RITE, MIDDLE to
specify this value. The color of the title is specified by using
the titlecolor() function. If the window is overlapped by any
other window it will be promoted to the top and be made the active
window.
Return: A non-zero value if successful.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
bordercolor(BLUE,LIGHTGRAY);
titlecolor(RED,LIGHTGRAY);
setborder(SINGLESIDES);
wnd = wframe(6,10,18,70,BLACK,LIGHTGRAY);
wtitle(wnd,TOP,LEFT," Top Left ");
wtitle(wnd,TOP,MIDDLE, " Top Middle ");
wtitle(wnd,TOP,RITE, " Top Right ");
wtitle(wnd,BOTTOM,MIDDLE," Bottom Middle ");
swait(5); wnd = wpop(wnd);
}
whide()
#include "pcpwproto.h"
int whide(WNDPTR *wnd);
Description: The whide() function will hide the window specified
with the WNDPTR pointer-handle. When the window is hidden it is
removed from the screen and all subsequent addresses to the window
are ignored. However, the window can be moved. The window can be
made visible again by using the wshow() function.
Returns: Non-zero value if successful.
Example
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
wnd = wframe(6,10,18,70,LIGHTGRAY,RED);
if (wnd == NULL) exit(3);
swait(5); whide(wnd); swait(3);
wndmove(wnd, 10,20); wshow(wnd);
swait(5); wnd = wpop(wnd);
}
wshow()
#include <pcwproto.h>
int wshow(WNDPTR *wnd) {
Description: The wshow() function will re-show a window that was
previously hidden with the whide function. The WNDPTR pointer
variable is a handle to the window to be re-shown.
Returns: A non-zero value if the function was successful.
Example: See previous example for whide() function.
wndmove()
#include <pcwproto.h>
int wndmove(WNDPTR *wnd, int row, int col);
Description: The wndmove() function will move the window specified
with the WNDPTR pointer variable to the specified coordinates, row &
col. The variables row and col are coordinates on the physical
screen and mark where the upper left corner of the window will be.
The wndmove() function checks to make sure that the window will fit
on to the physical screen and if not, will adjust the coordinates so
that it will fit.
Returns: A non-zero result if the move was successful.
Example:
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
int lcv;
wnd = wexplode(1,1,5,20,RED,LIGHTGRAY);
if (wnd == (WNDPTR *) 0) exit(3);
wtitle(wnd,TOP,MIDDLE, " Moving! ");
for (lcv = 1; lcv < 11; lcv++) {
wndmove(wnd,lcv*2,lcv*5);
rest(9);
}
wnd = wpop(wnd);
}
w_chg_attr()
#include <pcwproto.h>
int w_chg_attr(WNDPTR *wnd,int row,int col,int fclr,int bclr,int count);
Description: The w_chg_attr() function will change the color
attributes starting at row and col coordinates INSIDE THE WINDOW
addressed by WNDPTR and repeated count times. This function is
useful for menus that use a color bar to indicate a selection.
If the change of attributes attempts to move outside of the
window the function is aborted and no change of attributes occurs.
Returns: A non-zero value if the function was successful.
Example: See the menudemo program: The menu functions make
extensive use of w_chg_attr.
wscroll()
#include <pcwproto.h>
int wscroll(WNDPTR *wnd, int action, int count);
Description: The wscroll() function will scroll the window
referenced by the WNDPTR pointer variable. The action flag
determines if the entire area of the window is scrolled or just the
area inside of the borders. Setting this parameter to 0 will scroll
the entire area of the window (this includes the borders). Setting
it to a non-zero value will scroll the area inside of the borders.
The count parameter will specify the number of rows to scroll as well
as the direction to scroll. When the count parameter is a positive
value the scrolling will be down, and when the count is a negative
value the scrolling will be up. Again, if the window is overlapped
by any other window it will be promoted to the top.
Returns: A non-zero value if successful.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
wnd = wpush(6,10,18,70); /* Save area on screen */
set_wnd_attr(wnd,RED,RED); /* Set window colors */
while(!kbhit()) {
wscroll(wnd,0,3); /* Scroll wnd down 3 lines */
wscroll(wnd,0,-3); /* Scroll wnd up 3 lines */
} getch(); wnd = wpop(wnd); /* Clear keyboard & remove wnd */
}
w_block_write()
#include <pcwproto.h>
int w_block_write(WNDPTR *wnd, int row, int col, char *block[]);
Description: The w_block_write() function will write an array of
strings to the window referenced by WNDPTR *, starting at the row &
column specified and continuing on a new line until the entire
array of strings has been written to the window or until no more
lines can be written into the window, whichever occurs first.
NOTE the array of strings must be NULL terminated. The color of
the text will be determined by the color used when the window was
defined or set by the set_wnd_attr() function.
Returns: A non-zero value if completed successfully. If the entire
array of strings could not be written to the window then a zero value
will be returned.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
static char *msgs[] = {
"Description: w_block_write will write an array of strings",
"into your window in one fell swoop. This is very convenient",
"and keeps you from having to set up loops to do this function",
NULL
};
WNDPTR *wnd;
bordercolor(BLUE,LIGHTGRAY);
titlecolor(BLACK,LIGHTGRAY);
wnd = wframe(6,5,12,75,RED,LIGHTGRAY);
wtitle(wnd, TOP,MIDDLE," w_block_write ");
w_block_write(wnd,2,CENTER,msgs);
keywait(10); wnd = wpop(wnd);
}
pcwinit()
#include <pcwproto.h> void pcwinit(int action);
Description: The pcwinit() function initializes the PC Windows
library functions. It is not necessary to call this function in every
program because almost all (but not all) of the functions in the
library check to see if the library has been initialized and call
pcwinit() if it has not. The integer parameter, action, is used to
notify PCW whether an automatic exit is desired. The default (if you
let PCW initialize for you) is to set an automatic exit to remove all
windows from the screen. To disable this feature you must invoke
pcwinit() with an action of NOEXIT before you invoke any other PCW
function. To invoke pcwinit() and install the automatic exit use the
manifest constant AUTOEXIT.
Returns: Nothing
Example:
#include <pcwproto.h>
void main(void) {
pcwinit(NOEXIT); /* or AUTOEXIT */
vcls();
qputs(10,1,RED,BLACK,"The library is initialized!");
}
clr_wnd()
#include <pcwproto.h>
int clr_wnd(WNDPTR *wnd, int action);
Description: The clr_wnd() function will clear the contents of a
window specified with the WNDPTR variable. The action
parameter specifies whether the area to be cleared includes the
border of the window or not. If this parameter is non-zero only the
area inside of the borders will be cleared, otherwise the borders
will be cleared too.
Returns: Non-zero value if successful.
Example:
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd1, *wnd2;
bordercolor(BLUE,LIGHTGRAY);
wnd1 = wframe(1,1,10,40,BLACK,BROWN);
wnd2 = wframe(5,15,15,55,BLACK,LIGHTGRAY);
keywait(5);
clr_wnd(wnd1,0); wputs(wnd1,1,1,"The borders were cleared");
keywait(10);
clr_wnd(wnd2,1); wputs(wnd2,1,1,"Borders are not cleared");
keywait(10);
wnd1=wpop(wnd1);swait(3);wnd2= wpop(wnd2);
}
set_wnd_attr()
#include <pcwproto.h>
void set_wnd_attr(WNDPTR *wnd, int fcolor, int bcolor);
Description: The set_wnd_attr() function can be used to change the
color attributes of a window. When a window is created the
attributes of that window are stored and used on all subsequent
accesses to the window. set_wnd_attr() allows these color attributes
to be changed after the window has been created so that subsequent
accesses to the window will now use the new color attributes.
Returns: Nothing
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
wnd = wpush(6,20, 18, 60);
wputs(wnd, 1, CENTER, "Lightgray on Black");
keywait(3);
set_wnd_attr(wnd,WHITE,RED);
wputs(wnd, 2, CENTER, "White on Red");
keywait(3); clr_wnd(wnd,0); keywait(3);
}
Quick Screen Routines
qputchar()
#include <pcwproto.h>
int qputchar(int row,int col,int fclr,int bclr,char ch);
Description: The qputchar() function writes the character (ch) to the
video screen at the specified row and column (col) using the
specified foreground color (fclr) and the specified background color
(bclr).
Returns: Non-zero value if successful.
Example:
#include <pcwproto.h>
void main(void) {
int rw, cl, cnt = 0;
vcls();
for (rw = 0; rw < 16; rw++) {
for (cl = 0; cl < 16; cl++) {
qputchar(5+rw,32+cl,BLUE,LIGHTGRAY,cnt++);
}
}
}
qfill()
#include <pcwproto.h>
int qfill(int ur,int uc,in lr,int lc,int fclr,int bclr,int chr);
Description: The qfill() function will fill a specified rectangular
area on the video screen with the specified characters (chr) in the
specified colors (fclr & bclr). The area on the screen to be
filled is demarcated by the upper row and upper column (ur & uc)
and lower row and lower column (lr & lc).
Returns: Non-zero value if successful.
Example:
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
wnd = wpush(6,10,18,70);
qfill(6,10,18,70,RED,RED); keywait(10);
wnd = wpop(wnd);
}
qbox()
#include <pcwproto.h>
int qbox(int urow, int ucol, int lrow, int lcol);
Description: The qbox() function will draw a box on the screen. The
characters used to draw the box are specified with the setborder()
function. The color of the box is specified with the bordercolor()
function.
Returns: Nothing
Example:
#include <pcwproto.h>
void main(void) {
int ur, uc, lr, lc;
vcls();
setborder(SINGLESIDES);
bordercolor(CYAN,BLACK);
for (ur=1,uc=1,lr=25,lc=80;ur < lr && uc < lc; ur += 1, uc += 4)
qbox(ur,uc,lr,lc);
}
qvchar()
#include <pcwproto.h>
int qvchar(int row,int col,int fclr,int bclr,char chr,int count);
Description: The qvchar() function repeats the specified character
(chr) count times vertically on the screen originating at row &
column (col) using the colors specified by fclr and bclr.
Returns: Non-zero value if successful.
Example:
#include <pcwproto.h>
void main(void) {
int row, col, chr;
vcls();
for (row=1,col=1,chr=33; row < 25; row++, col+=3,chr++)
qvchar(row,col,7,0,chr,25-row);
}
qhchar()
#include <pcwproto.h>
int qhchar(int row,int col,int fclr,int blcr,char chr,int count);
Description: The qhchar() function repeats the specified character
(chr) count times horizontally on the screen originating at row and
column (col) using the color attributes specified by fclr and bclr.
Returns: Non-zero value if successful.
Example:
#include <pcwproto.h>
void main(void) {
int row, col, chr;
vcls();
for (row=1,col=1,chr=65; row < 25;row++,col+=3,chr++)
qhchar(row,col,4,0,chr,80-col);
}
qputs()
#include <pcwproto.h>
int qputs(int row,int col,int fclr,int bclr,char *string);
Description: The qputs() function writes the character string
(*string) to the video display at the coordinates (row & col) in the
specified color attributes (fclr & bclr). No character filtering
takes place and no line-feed character is inserted at the end of the
string.
Returns: A non-zero value if successful.
Example:
#include <pcwproto.h>
void main(void) {
char *string = "Hello World...PCW is here!";
vcls();
qputs(12,CENTER,WHITE,BLACK+BLINK,string);
}
qvputs()
#include <pcwproto.h>
int qvputs(int row, int col, int fclr, int bclr, char *string);
Description: The qvputs() function writes the character string
(*string) to video display vertically originating from row and column
(col) with the specified color attributes (fclr & bclr).
Returns: A non-zero value if successful.
Example:
#include <pcwproto.h>
void main(void) {
int lcv,mxr,mxc;
if (!chk_video_state(&mxr,&mxc)) exit(3);
for (lcv = 1; lcv <= mxc; lcv++)
qvputs(1,lcv,15,0,"Hello World PCW Here!");
}
q_block_write()
#include <pcwproto.h>
int q_block_write(int row,int col,int fclr,int blcr,char *block[]);
Description: The q_block_write() function will accept an array of
pointers to character strings (*block[]) and write the character
strings to the video display in one fell swoop. The first character
string is written at row and col and the row is incremented before
each string is written to the display. The color is specified with
the fclr and bclr variables. The array of pointers should be NULL
terminated.
Returns: A non-zero value if successful.
Example:
#include <stdio.h>
#include <pcwproto.h>
static char *block[] = {
"q_block_write() make writing arrays of character",
"strings a breeze because you do not have to set",
"up loops to do it yourself",
NULL
};
void main(void) {
vcls();
q_block_write(10,25,4,0,block);
}
qprintf()
#include <pcwproto.h>
int qprintf(int row,int col,int fclr,int bclr,char *format,...);
Description: The qprintf() function writes a formatted string to the
video display much the same as the standard printf() function does,
however, no character filtering takes place. This means newline
characters are not interpreted and are written to the video display.
The string is written at the row and column (col) specified using the
color attributes specified by the fclr and bclr variables.
Returns: A non-zero value if successful completed.
Example:
#include <pcwproto.h>
void main(void) {
char *format = "qprintf is very quick and fast. Row = %0d";
int row;
for (row=1,row < 26; row++)
qprintf(row,CENTER,BLUE,LIGHTGRAY,format,row);
}
scroll()
#include <pcwproto.h>
int scroll(int ur,int uc,int lr,int lc,int fclr,int bclr,int count);
Description: The scroll() function will scroll the rectangular area
of the screen demarcated by the ur uc (upper row & col-upper left
corner) and the lr & lc (lower row & col - lower right corner)
variables. The scroll function will not cause flicker as does the
BIOS scrolling on some video adapters. As the demarcated area is
scrolled the color attributes fclr and bclr specify the color of the
blanked lines added to the scroll region. The count variable
determines the number of lines scrolled. Furthermore, the count
variable determines the direction. If the count variable is positive
the scroll region is scrolled downward and if negative the scroll
region is scrolled up.
Returns: A non-zero value if completed successfully.
Example:
#include <pcwproto.h>
void main(void) {
WNDPTR wnd;
wnd = wpush(6,10,18,70);
while(!keypressed()) {
scroll(6,10,18,70,RED,RED, 3);/* Scroll region down 3 */
scroll(6,10,18,70,BLUE,BLUE,-3);/* Scroll region up 3 lines */
} keybrd_flush();
wnd = wpop(wnd);
}
getattr()
#include <pcwproto.h>
int getattr(int row, int col);
Description: The getattr() function returns the color attribute at
the specified row and column.
Returns: The color attribute at row and column. Returns -1 if
unsuccessful.
getchr()
#include <pcwproto.h>
int getchr(int row, int col);
Description: The getchr() function returns the character at the
specified row and column. Returns a -1 if unsuccessful.
Bios Dependant Functions
get_cursor_size()
#include <pcwproto.h>
void get_cursor_size(int *tline, int *bline);
Description: The get_cursor_size() function returns the beginning and
ending scan lines of the text cursor in the integer pointers. You
should use this function at the beginning of your program if you are
planning to turn the cursor off at any time during the execution of
your program.
Returns: Nothing.
Example:
#include <pcwproto.h>
void main(void) {
int tl, bl;
vcls(); get_cursor_size(&tl, &bl);
set_cursor_size(0,0); keywait(10);
set_cursor_size(tl,bl);
}
set_cursor_size()
#include <pcwproto.h>
void set_cursor_size(int tline, bline);
Description: The set_cursor_size() function will set the beginning
and ending scan lines of the text cursor. This function is used in
conjunction with get_cursor_size() function to turn the cursor on
and off frequently. If both scan line values passed to
the set_cursor_size function are zero the cursor will be turned off.
Returns: Nothing
Example: See above example.
get_cursor_pos()
#include <pcwproto.h>
void get_cursor_pos(int *row, int *col);
Description: The get_cursor_pos() returns the position of the text
cursor on the current video page in the two integer pointers.
Returns: Nothing
Example:
#include <pcwproto.h>
void main(void) {
int row, col
set_cursor_pos(12,40);
get_cursor_pos(&row, &col);
qprintf(12,CENTER,RED,0,"Cursor Row = %d Cursor Col = %d",row,col);
}
set_cursor_pos()
#include <pcwproto.h>
void set_cursor_pos(int row, int col);
Description: The set_cursor_pos() function sets the cursor position
to the the row and column specified in the argument list.
Returns: Nothing.
Example: See above expample.
switchpage()
#include <pcwproto.h>
void switchpage(int videopage);
Description: The switchpage() function will switch the current video
page to the one specified by the videopage parameter. With adapters
such as the CGA, EGA, and VGA there are more than one video page in
which to display video output, however only one video page at a time
may be displayed. It is possible, therefore, to build a screen in
the background on a video page not displayed and then switch to it.
The number of video pages depend on the video adapter you are using
and the video mode you are using. See also the setpage() function.
Returns: Nothing
Example:
#include <pcwproto.h>
void main(void) {
int i;
pcwinit();
setpage(1);
for (i=1;i<25;i++) qputs(i,CENTER,RED,BLACK,"Hello World!");
keywait(5);
switchpage(1); keywait(5);
switchpage(0);
}
vcls()
#include <pcwproto.h>
void vcls(void);
Description: The vcls() function will clear the video display and
set the color attributes to lightgray on black much like the DOS cls
command. However, unlike the DOS cls command if your display is
using the EGA 43 line mode or the VGA 50 line mode all 25, 43, or 50
lines will be cleared.
Returns: Nothing.
vgetmode()
#include <pcwproto.h>
void vgetmode(int *cols, int *mode, int *activepage);
Description: The vgetmode function is used to return the number of
columns, the video mode, and the active video page of the current
display.
Returns: Nothing.
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
int cols,mode,ap;
vgetmode(&cols,&mode,&ap);
printf("The mode is %d, the number of columns is %d, acivepage is %d",
mode, cols, ap);
}
vgetattr()
#include <pcwproto.h>
int vgetattr(void);
Description: The vgetattr() function returns the color attribute on
the video display at the cursor location.
Returns: The color attribute.
Example:
#include <pcwproto.h>
void main(void) {
int attr, chr;
set_cursor_pos(1,1);
attr = vgetattr();
chr = vgetchr();
printf("Attribute = %x, Character = %c",attr,chr);
}
vgetchr()
#include <pcwproto.h>
int vgetattr(void);
Description: The vgetchr() function returns the character from the
video display at the current cursor position.
Example: See above example.
vsetmode()
#include <pcwproto.h>
void vsetmode(int mode);
Description: The vsetmode() function will set the video mode of the
EGA/VGA/CGA/MDA adapter. For color adapters the video mode used for
text processing is mode 3, while for monochrome monitors the
most frequently used mode is mode 7. When the mode is set the
screen is cleared and the contents are lost.
Example:
#include <pcwproto.h>
void main(void) {
pcwinit(NOEXIT);
(_monitor == COLOR) ? vsetmode(3) : vsetmode(7);
}
set_vga_scan_lines()
#include <pcwproto.h>
void set_vga_scan_lines(int arg);
Description: Sets the number of scan lines to be used on the display
of a VGA unit. The value for arg can be one of three: CGA200,
EGA350, VGA400. Using CGA200 will cause the VGA adapter to use 200
scan lines for its display which will look just like a CGA display.
Using EGA350 will cause 350 scan lines to be used which is equivelant
to an EGA display and VGA400 will use 400 scan lines for VGA
resolution (which is what you paid for).
Example:
#include <stdlib.h>
#include <pcwproto.h>
void main(void) {
int lcv;
for (lcv = 0; lcv <= EGA400; lcv++) {
set_vga_scan_lines(lcv);
system("dir");
keywait(10);
}
}
fload()
#include <pcwproto.h>
void fload(int block, int font);
Description: The fload() function will load one of the three
standard fonts on the EGA/VGA and reprogram the video controller and
will ensure the cursor works correctly. On all adapters an 8x8 font
can be loaded to create 43 text line mode on the EGA and 50 text line
mode on the VGA. An 8x14 font can be loaded on the EGA/VGA, however
this will cause 28 text line mode on the VGA unless the number of
scan lines is set to 350. If a VGA is active an 8x16 font can be
loaded (this is the normal font for VGA).
The value used for the 'block' parameter can be 0-3 with 0 being the
most used. The legitimate values for 'font' are 8, 14, and 16.
Example: (Assumes an EGA/VGA)
#include <stdlib.h>
#include <pcwproto.h>
void main(void) {
system("dir");
fload(0,8);
keywait(10);
(_adaptor == EGA) ? fload(0,14) : fload(0,16);
}
download_rom_font()
#include <pcwproto.h>
int download_rom_font(int font, char *buffer);
Description: The download_rom_font() function will copy the
specified font, either 8x14 or 8x16, from the EGA or VGA ROM into the
user supplied buffer. Use the manifest constant values EGA14 and
VGA16 for the font parameter. The user supplied buffer must be large
enough to hold (16 * 256) bytes for the 8x16 font or (14 * 256) bytes
for the 8x14 font.
Returns: The number of bytes per character are returned if the
function is successful, otherwise zero is returned.
Example: See example below.
load_user_font()
#include <pcwproto.h>
int load_user_font(int bpc,int blk,int nchrs,int fchr,char *buffer);
Description: The load_user_font() function is used to load a
user's "soft font" into the EGA/VGA registers. The parameters
are explained as follows:
1. bpc - bytes per character, use either EGA14 or VGA16.
2. blk - video block to load the font (usually 0).
3. nchrs - number of characters in the font buffer.
4. fchr - first character in font buffer
5. *buffer - the font buffer (can be obtained by using
download_rom_font()).
Following the load of a user font, a video reset will reload the
default ROM font.
Returns: A non-zero value is returned if the function is successful.
Example:
void main(void) { /* make 'a' into 'b' and 'b' into 'c'.... */
int i, j, k, x;
static char ftable[16*256];
pcwinit(NOEXIT);
if (_adaptor > CGA) {
k = (_adaptor == EGA) ? EGA14 : VGA16;
if ((k = download_rom_font(k, ftable)) != 0) {
for (i = 'a'; i <= 'z'; i++) {
j = i * k;
x = j + k;
while (j < x) {
ftable[j] = ftable[j + k];
j++;
}
}
load_user_font(k, 0, 256, 0, ftable);
}
}
else puts("Must have an EGA or VGA to run this demo");
}
get_ega_palette()
#include <pcwproto.h>
char *get_ega_palette(int mode);
Description: Makes an internal copy of the values in the EGA palette
regsisters specified by mode into an internal buffer and returns a
pointer to the buffer. The size of the buffer is 17 bytes and
represents the values in the 16 EGA palette registers with the
overscan regsiter. The values in this table may be modified and
reloaded into the palette registers using the load_ega_palette()
function. Together these functions allow you to use all 64 of the
available colors in text mode on the EGA/VGA.
Returns: Pointer to internal register buffer, NULL if unsuccessful.
Example: See example below.
set_palette()
#include <pcwproto.h>
void set_palette(int attribute_register, int color);
Description: Sets the attribute register in the internal register
table to the specified color. The attribute_register value must be 0
through 15 and the color can be 0 through 63. This function allows
you to set all 16 palette registers to desired colors in memory and
use those colors with load_ega_palette().
load_ega_palette()
#include <pcwproto.h>
void load_ega_palette(void);
Description: Loads the internal attribute register table into the
EGA/VGA palette registers causing any changes in color to immediately
take effect.
set_load_palette()
#include <pcwproto.h>
void set_load_palette(int palette_register, int color);
Description: Changes the value in the internal attribute register
table to the specified color and reloads the EGA/VGA palette
registers immediately. This is equivalent to calling set_palette()
followed by a call to load_ega_palette().
Example:
#include <pcwproto.h>
void main(void) {
WNDPTR *wnd;
int i;
if (get_ega_palette(22) != (char *) 0) {
bordercolor(RED,RED);
wnd = wframe(6, 20, 18, 60, RED, RED);
for (i = 0; i < 64; i++) {
set_load_palette(RED, i);
swait(1);
}
}
}
set_int24()
#include <pcwproto.h>
int set_int24(void);
Description: The set_int24() function will install a custom critical
interrupt handler under the control of your program. The critical
interrupt handler will then be responsible for disk errors, printer
time outs or any other device type error. When an error occurs the
critical interrupt handler will open a window in the current video
page, display a title with the error message, display a menu, and a
few words of encouragement, and if the error was a disk error, a
message appears in the middle of the window identifying the offending
disk(ett) drive. When a selection is made control returns to DOS and
then back to your program (hopefully), or the program is aborted
depending on the user's choice. In all cases the window is removed
from the screen and the hated message "Abort, Retry or Ignore" is
avoided. Upon return to DOS the interrupt vector will automatically
be reset by DOS.
Returns: Non-zero value if successful
Example:
#include <stdio.h>
#include <pcwproto.h>
void main(void) {
FILE *fp;
char *filename = "a:dummy.txt";
pcwinit(0);
if (set_int24() ) {
puts("Please open the door to drive A: ");
puts("and press a key to continue");
while(!keypressed()); keyin();
fp = fopen(filename, "r");
if (fp == NULL) puts("Could not open file");
}
}
set_int29()
The set_int29() function captures the DOS fast output interrupt,
interrupt 29h so that when DOS is writing characters out from standard
output or standard error devices, the output will be captured in a PCW
window.
The reset_int29() function will remove the hooks that set_int29() used
to capture DOS fast output. NOTE!!!! If you use set_int29() anywhere
in a program you must call reset_int29() before the program ends. If
you do not most likely your PC will lock up.
NOTE: the set_int29() function does not work at all when using Zortech
and limps along when using Power C. Using Turbo C and MSC there were
no problems at all. Furthermore, the set_int29() function does not
work at all under Power C when compiled in the small memory model.
Example:
#include <stdio.h>
#include <pcwproto.h>
int main ( void ) {
WNDPTR *wnd;
wnd = wframe(3, 1, 22, 80, BLACK, LIGHTGRAY);
set_int29();
system("type pcw.doc");
reset_int29();
wnd = wpop( wnd );
return 0;
}
Mouse Functions
init_mouse()
#include <pcwproto.h>
int init_mouse(void);
Description: The init_mouse() function will initialize the mouse
hardware and software driver and return a non-zero value if the mouse
driver & hardware are present. A global variable, mpresent, will be
set to a non-zero value if the mouse is present. If you want to use
the mouse in your program you should call init_mouse() and examine
the value of the mpresent variable whenever you wish to determine if
the mouse is present. It would also be a good practice to
call init_mouse at the end of your program to reset the mouse driver
for the next program. Calling init_mouse() a second time will reset
the mpresent variable to a FALSE value. Calling init_mouse()
always hides the mouse cursor.
Returns: A non-zero value if the mouse is present.
Example: See the program MOUSDEMO.C for exhaustive examples.
get_mpressed()
#include <pcwproto.h>
int get_mpressed(int button);
Description: The get_mpressed() function returns the number of times
a mouse button has been pressed since the last call to
get_mpressed(). Use the manifest constants LEFTM, and RITEM to
specify which button you want to know about. The range can be
from 0 to 65535 and the Mouse driver will not check for overflow.
Once called for a particular button the count for that button is
cleared.
Example: See MOUSDEMO.C for exhaustive examples.
get_mreleased()
#include <pcwproto.h>
int get_mreleased(int button);
Description: The get_mreleased() function is the compliment of the
get_mpressed() function in that it returns the number of times the
Mouse key specified by button has been released since the last call
to get_mreleased. Use the manifest constants RITEM and LEFTM to
specify the button that you want to know about. The range can be
from 0 to 65535 and the driver does not check for overflow.
Example: See MOUSDEMO.C for examples.
show_mouse()
#include <pcwproto.h>
void show_mouse();
Description: The show_mouse() function will turn on or show the
Mouse cursor. Once you have initialized the Mouse with init_mouse()
you must use show_mouse() to make the mouse cursor visible. If you
have defined a region for the Mouse with mframe() the Mouse cursor
will appear in the region. Making subsequent calls to show_mouse()
will have no effect.
Examples: See MOUSDEMO.C and MENUDEMO.C
hide_mouse()
#include <pcwproto.h>
void hide_mouse();
Description: The hide_mouse() function will hide the mouse cursor.
Hiding the Mouse is necessary when using windows or quick screen
writes as there is no way to tell where the Mouse is. If your
program uses the Mouse you should test the presence of the Mouse by
checking the value of the global variable, mpresent, and turn off
the Mouse if the value is non-zero. Subsequent calls to hide_mouse()
will have no effect.
Examples: See MOUSDEMO.C, MENUDEMO.C, PDEMO.C, and LDEMO.C
get_mpos()
#include <pcwproto.h>
void get_mpos(int *row, int *col, int *button_status);
Description: The get_mpos() function is primarily intended
to retrieve the position of the Mouse cursor, but it can also be used
to retrieve the button status. When called the Mouse position
is returned in the row & col pointers and the button status is
also returned. The values returned for Mouse position are correct
for any video mode. The possible return values for button_status
and their meanings are as follows:
1 = Left Mouse Button pressed.
2 = Right Mouse Button pressed.
3 = Both Mouse Buttons pressed.
Examples: See MOUSDEMO.C
set_mpos()
#include <pcwproto.h>
void set_mpos(int row, int col);
Description: The set_mpos() function sets the Mouse cursor position
on the video display.
set_mtype()
#include <pcwproto.h>
void set_mtype(int ctype, int arg1, int arg2);
Description: The set_mtype() function will set the Mouse cursor
type. The two cursor types are the hardware cursor or the software
text cursor (Mouse soft cursor). If ctype is 0, set_mtype() selects
the software text cursor and arg1 and arg2 must select screen and
cursor mask (SEE MOUSDEMO.C). If ctype is equal to 1 the hardware
cursor is used and arg1 and arg2 select the beginning and ending scan
lines for the cursor much like that of set_cursor_size(). You may
set the Mouse cursor type then call show_mouse() to display the
results.
Examples: See Mousdemo.C also.
#include <pcwproto.h>
void main(void) {
int ctype=1,arg1=1,arg2=0x7;
int tl, bl;
/* Take over hardware cursor */
/* See MOUSDEMO.C for examples of using soft cursor */
init_mouse(); get_cursor_size(&tl,&bl);
set_mtype(ctype,arg1,arg2); show_mouse();
keywait(60);
init_mouse(); /* Reset Mouse */
set_cursor_size(tl,bl); /* Set cursor size back */
}
save_mouse_state()
#include <pcwproto.h>
char *save_mouse_state(void);
Description: Use the save_mouse_state() function to save the state
of the Mouse driver before spawning to another program that uses or
may use the Mouse also. The save_mouse_state() function returns a
pointer to a buffer where the mouse state information is held.
Upon returning from the child process you may make a call to the
restore_mouse_state() function using the pointer to the saved area.
Returns: A pointer to the saved buffer. NULL if memory could not be
allocated.
restore_mouse_state()
#include <pcwproto.h>
void restore_mouse_state(char *buffer);
Description: The restore_mouse_state() function uses a pointer to a
buffer allocated by the save_mouse_state() function to restore the
state of the Mouse driver after returning from a child process or a
system() function call. The memory allocated for the buffer is then
deallocated and returned to the free pool. Upon completion the Mouse
is as it was when the Mouse state was saved.
Returns: Nothing.
Keyboard Functions
With this release of PCW the keyboard functions have been completely
re-written to more closely integrate keyboard events and mouse events.
Furthermore, support for console redirection has been added. Any
program using any of the PCW keyboard functions should include the
header file KEYS.H. Also, the return values from these functions have
been changed to better isolate the special keys such as the function
keys and the arrow keys. These return values are of type int and most
times when special keys are involved are not in the range of normal
ASCII characters. This has caused problems with the functions declared
in CTYPE.H such as toupper(), tolower(), isalpha(), and so on. Most
notably the functions (macros) in Microsoft C and Turbo C have problems
with the return values from the keyboard functions because they use a
table driven method of validation of the characters, and when the
integer value from the keyboard function are not in the range of normal
characters, problems arise. To alleviate this problem a macro,
ischar(), is defined in PCWPROTO.H. An example use of this macro is
provided:
if ( ischar(ch) ) ch = toupper(ch);
return ( ischar(ch) ? isalpha(ch) : 0 );
Keypressed()
#include <keys.h>
#include <pcwproto.h>
int keypressed(void);
The keypressed() function was originally used to determine if a
character was waiting in the keyboard que, but now is used to determine
if one of several input events is true. The keypressed() function can
be used to determine if console standard input has been redirector, or
if a character is waiting in keyboard que buffer, or if a mouse key has
been pressed. The return values from keypressed signify which event is
true:
0 = No Event.
1 = Console Standard Input is Redirected.
2 = Character is pending in keyboard que buffer.
3 = A mouse key has been pressed.
function c
readkey()
#include <pcwproto.h>
int readkey(void);
Description: The readkey() function will (1) return the most recent
mouse key that was pressed ( LEFT_MOUSE_KEY, RITE_MOUSE_KEY,
BOTH_MOUSE_KEY ), (2) return the character that from a file that has
been redirected to standard input, and (3) return a pending character
from the keyboard que buffer. If none of these events has occured when
keyin() is called, keyin() will wait until one does occur. The Ctrl-C
interrupt has no effect on this function.
isxkeybd()
#include <keys.h>
#include <pcwproto.h>
int isxkeybd(void);
Description: The isxkeybd() function determines if the BIOS supports
an extended keyboard or not. If the BIOS does support an extended
keyboard it does not mean that an extended keyboard is attached to
the computer, but it would be reasonable to assume that one is. If
the BIOS supports the extended keyboard your program can make use of
the F11 & F12 keys with other PCW keyboard functions.
keywait()
#include <keys.h>
#include <pcwproto.h>
int keywait(int seconds);
Description: The keywait() function will delay program execution for
the specified number of seconds or until a key is pressed, keyboard
or mouse. keywait() will return a -1 if time elapsed with no key
pressed and will return the keyboard character when a key is pressed.
keyin()
#include <keys.h>
#include <pcwproto.h>
int keyin(void);
Description: With this release of PCW keyin() is an alias for
readkey().
keybrd_flush()
#include <pcwproto.h>
void keybrd_flush(void);
Description: The keybrd_flush() function will flush the keyboard
buffer of all characters entered since the last access to the
keyboard. This is useful if you do not wish users of your
programs to enter keystrokes ahead of your prompts.
get_chars()
#include <keys.h>
#include <pcwproto.h>
int get_chars(int rw,int cl,int fclr,int bclr,int len,char *buffr);
Description: The get_chars() function will accept buffered input
from the keyboard at the specified row and column using the
foreground and background colors specified by fclr and bclr. The
maximum number of characters that may be entered are specified by
len and the characters themselves are stored in *buffr. The
get_chars() function supports the left and right arrow keys,
destructive backspacing, the home and end keys, and inserting and
deleting characters. When get_chars() detects an error the bell
will be sounded. In addition if *buffr contains a string it will be
displayed at row and column when get_chars() is called and the
string may be edited.
Returns: Returns zero when the enter key is struck and will return
the Esc characters when the Esc key is pressed.
ENVIRONMENT FUCNTIONS
The environment function in PCW are used mostly for internal purposes
of PCW, however, some of them could be useful to your programs when
used with PCW. Therefore, I document them here.
getpage()
#include <pcwproto.h>
#int getpage(void);
Description: The getpage() function returns the current video page
in which PCW is operating. The IBM PC color video, when in text
mode, can operate on 4 to 16 video pages depending on the video
adapter in use and the text mode being used. It is possible with PCW
to set a video page with the setpage() function and write to a video
page not displayed and later display it with the switchpage()
function.
getpagesize()
#include <pcwproto.h>
int getpagesize(void);
Description: The getpagesize() function returns current size of
a video memory page. Normally this is 4096 (when using 25 X 80 text
mode), but it could be different if your monitor is using the EGA 43
line mode or the VGA 50 line mode. This function is used extensively
within PCW.
setpage()
#include <pcwproto.h>
int setpage(int page);
Description: The setpage() function is used to set the current video
page for PCW to work in. Normally the video page is set to zero by
the BIOS when the PC is booted up. PCW initializes this value to
what the BIOS is using when your program begins execution. It is
possible to force PCW to use another video page for screen
writing while displaying the current video page (screen writing in
the background), and later switch to the video page where all the
writing was done. This gives the appearance of instant screen
writing.
ispcwinit()
#include <pcwproto.h>
int ispcwinit(void);
Description: The ispcwinit function is used internally by PCW to
determine if the kernel code of PCW has been initialized. When your
program calls one of PCW's functions a check is made to see if the
kernal code was initialized, and, if it has not, the call to
initialize PCW is made. This keeps you from having to remember to
initialize PCW at the beginning of each of your programs.
chk_video_state()
#include <pcwproto.h>
int chk_video_state(int *max_rows, int *max_cols);
Description: The chk_video_state() function is a very useful one in
that it will do the follow for you:
1. Initialize PCW.
2. Return a value indicating whether or not you can use PCW
with the current video environment.
3. Returns the maximum number of rows and columns on the video
display.
The main purpose of chk_video_state() is to determine whether the
video display is in text mode or not. If the display is in graphics
mode PCW will not, and can not do its job. If successful, the
integer pointers, max_rows & max_cols are returned with the maximum
number of rows and columns on the video display. For example, if
your display was in 40 column mode this would be reflected in
*max_cols, and if the display was in EGA 43 line mode this would
be reflected in *max_rows.
getscrnseg()
#include <pcwproto.h>
unsigned getscrnseg(void);
Description: The getscrnseg() function will return the segment used
to address the video display memory. If the display is a monochrome
the getscrnseg() function will return the value (in hex) 0xB000 and
will return 0xB800 if a color monitor is in use. getscrnseg() is
used internally by PCW.
MISCELLANEOUS FUNCTIONS
_sound()
#include <pcwproto.h>
void _sound(unsigned frequency);
Description: The _sound() function will create a tone with the
specified frequency. The tone will continue to sound until a call to
the _nosound() function is made.
_nosound()
#include <pcwproto.h>
void _nosound(void);
Description: The _nosound() function will discontinue the tone
generated by the _sound() function.
rest()
#include <pcwproto.h>
void rest(unsigned timer_ticks);
Description: The rest() function will suspend the execution of the
program for the specified number of timer_ticks. Approximately 18
timer_ticks occur each second so calling rest with a value of 9 will
be roughly 1/2 a second.
swait()
#include <pcwproto.h>
void swait(unsigned seconds);
Description: The swait() function will suspend program execution
for the specified number of seconds. swait() functions very much
like sleep() in Turbo C and Power C and has been included so there
will be a delay function for MSC as well.
_delay()
#include <pcwproto.h>
void _delay(unsigned milliseconds);
Description: The _delay() function will suspend program execution
for the specified number of milliseconds. To gain this measure of
accuracy _delay was written in assembler and programs the 8253 timer
chip on the motherboard of the PC. Channel 2 of the 8253 was used
for the timing delay because channel 0 is used for the BIOS Time of
Day Count and channel 1 is used for memory refresh. Channel 2 is
also used to produce sounds on the PC (this is how the _sound()
function works). Therefore, using sound functions and _delay()
should be mutually exclusive.
titlecolor()
#include <pcwproto.h>
void titlecolor(int fcolor, int bcolor);
Description: The titlecolor() function is used to set the title
colors when titling a window. If you do not use the titlecolor()
function before titling a window the color used will be the default
color of lightgray on black.
bordercolor()
#include <pcwproto.h>
void bordercolor(int fcolor, int bcolor);
Description: The bordercolor() function is used to set the color
attributes for window borders when using the wframe(), qbox(), and
wexplode() functions. If you do not use bordercolor() to set the
attributes the default of lightgray on black will be used.
setborder()
#include <pcwproto.h>
void setborder(int border_type);
Description: The setborder() function will set the border type used
in all subsequent calls to qbox(), wframe(), and wexplode(). Use the
manifest constants DOUBLEALL, SINGLEALL, SINGLESIDES, DOUBLESIDES, or
NOSIDES to specify the type of border you want to use. The default
border type is DOUBLEALL.